package util;

import java.io.IOException;
import java.io.InterruptedIOException;

import javax.xml.bind.JAXBException;

/**
 * An interface between two entities that facilitates communication between them through {@link MBMessage}s.
 * @author Bitidork
 *
 */
public interface MBMessageChannelInterface {
	/**
	 * Reads a message over the channel.
	 * @return The message that was read.
	 * @throws InterruptedIOException if the read was interrupted.
	 * @throws JAXBException if an error was encountered while unmarshalling a message.
	 * @throws IOException if an error was encountered while reading data from the channel.
	 * @throws InterruptedException TODO
	 */
	public MBMessage read( ) throws InterruptedIOException, JAXBException, IOException, InterruptedException;
	
	/**
	 * Writes the message to the channel's output stream and flushes it.
	 * @param msg The message to write.
	 * @throws JAXBException if an error was encountered while marshalling the message.
	 * @throws IOException if an error was encountered while writing the message string, or if {@value util.MBMessage#ENCODING} was an unsupported encoding.
	 * @throws InterruptedException TODO
	 */
	public void write( final MBMessage msg ) throws JAXBException, IOException, InterruptedException;
	
	/**
	 * Closes this channel. This operation should be best-effort, and exceptions ignored.
	 */
	public void close( );
}
